<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html>
<html>
<head>
<title>SCM Workbench - User Guide</title>
<meta charset="UTF-8" /> 
<link rel="stylesheet" type="text/css" href="scm-workbench.css" />
<link rev="made" href="mailto:barry@barrys-emacs.org" />
</head>
<body>
<h1><img src="scm-workbench_files/wb.png" width="64px" height="64px" /> SCM Workbench - User Guide</h1>

<p>User guide for the Source Control Mangement (SCM) Workbench.</p>

<p><b>User Guide Sections</b></p>

<ul>
<li><a href="scm-workbench.html">Scm Workbench</a> - gettings started and common shared features.</li>
<li><a href="scm-workbench-git.html">Git in Scm Workbench</a> - git specific menus and features.</li>
<li><a href="scm-workbench-hg.html">Mercurial (hg) in Scm Workbench</a> - Mercurial specific menus and features.</li>
<li><a href="scm-workbench-svn.html">Subversion (svn) in Scm Workbench</a> - Subversion specific menus and features.</li>
</ul>

<p><b>Table of Contents</b></p>

<ul>
<li><a href="#getting_started">Getting started</a></li>
<li><a href="#main_window">SCM Workbench Window</a></li>
<li><a href="#menus">Workbench Common Menus</a></li>
<li><a href="#project_add">Add Project Wizard</a></li>
</ul>

<h2><a name="getting_started">Getting started</a></h2>

<ol>
<li>Make sure you have all the <a href="#optional_software">Optional software</a> you need installed.</li>
<li>Configure the <a href="#file_preferences">Preferences</a> to you taste. For example which editor to use.</li>
<li>Add projects using the <a href="#project_add">Add Project Wizard</a></li>
<li>Explore the menus and toolbars to see what you can do.</li>
</ol>

<h2><a name="main_window">Workbench Window</a></h2>

<figure>
    <img src="scm-workbench_files/wb_main_window.png" />
    <figcaption>Main Window</figcaption>
</figure>

<p>The SCM Workbench window is split into three main areas. The top area is like
a file and folder explorer.
</p>

<p>Use the left hand tree control to change between projects and folders and
use the right hand list control to work with files. You can change the information
shown using the <a href="#menu_view">View</a> menu.
</p>

<p>The bottom panel is used to show messages. In the example below the result of
a git pull.
</p>

<p>Use the toolbar to access frequently used commands.</p>

<p>The status bar will show the progress of long running operations like
push and checkin commands.</p>


<p>The filename filter is used to focus in on a few files.</p>
<p>
<figure>
    <img src="scm-workbench_files/wb_main_window_filter.png" />
    <figcaption>Filename filter</figcaption>
</figure>
</p>
<p>Type a part of the name into the text box to show only files that contain what you type in the name.
</p>

<p>Click the X icon to clear the filter string and show all files.
</p>

<h2><a name="menus">SCM Workbench Menus</a></h2>

<p>All of the menu items in SCM Workbench are described below. Click on the menu item to scroll to its description.
</p>

<p>The menus and toolbars are changed to reflect the needs of the selected project.</p>

<figure>
<table>
<tr><td class="menu_active">File</td>
    <td class="menu_active">View</td>
    <td class="menu_active">Folder Actions</td>
    <td class="menu_active">File Actions</td>
    <td class="menu_active">Project</td>
    <td class="menu_active">Help</td></tr>
<tr>
<td valign="top">
    <div class="menu_dropdown">
    <table><!-- File -->
    <tr><td><a href="#file_preferences">Preferences…</a></td></tr>
    <tr><td><a href="#file_view_log">View Log</a></td></tr>
    <tr><td><a href="#file_exit">Exit</a></td></tr>
    </table></div></td>
<td valign="top">
    <div class="menu_dropdown">
    <table><!-- View -->
    <tr><td><a href="#view_show_control_changed">Show Controlled and Changed files</a></td></tr>
    <tr><td><a href="#view_show_control_unchanged">Show Controlled and Not Changed files</a></td></tr>
    <tr><td><a href="#view_show_uncontrol">Show Uncontrolled files</a></td></tr>
    <tr><td><a href="#view_show_ignored">Show Ignored files</a></td></tr>
    <tr><td><hr /></td></tr>
    <tr><td><a href="#view_unified_diff">Unified diff</a></td></tr>
    <tr><td><a href="#view_side_by_side_diff">Side by side diff</a></td></tr>
    </table></div></td>
<td valign="top">
    <div class="menu_dropdown">
    <table><!-- Folder Actions -->
    <tr><td><a href="#folder_action_command_shell">Command Shell</a></td></tr>
    <tr><td><a href="#folder_action_file_browser">File Browser</a></td></tr>
    </table></div></td>
<td valign="top">
    <div class="menu_dropdown">
    <table><!-- File Actions -->
    <tr><td><a href="#file_action_edit">Edit</a></td></tr>
    <tr><td><a href="#file_action_open">Open</a></td></tr>
    </table></div></td>
<td valign="top">
    <div class="menu_dropdown">
    <table><!-- Project -->
    <tr><td><a href="#project_add">Add…</a></td></tr>
    <tr><td><a href="#project_settings">Settings…</a></td></tr>
    <tr><td><hr /></td></tr>
    <tr><td><a href="#project_delete">Delete…</a></td></tr>
    </table></div></td>
<td valign="top">
    <div class="menu_dropdown">
    <table><!-- Help -->
    <tr><td><a href="#help_user_guide">User Guide…</a></td></tr>
    <tr><td><a href="#help_about">About…</a></td></tr>
    </table></div></td>
</tr></table>
<figcaption>Common menus.</figcaption>
</figure>


<h3><a href="#menus">Menu:</a> <a name="menu_file">File</a></h3>
<h4><a name="file_preferences"><a href="#menus">Menu:</a> File » Preferences…</a></h4>

<h5>Projects preferences</h5>
<figure>
    <img src="scm-workbench_files/wb_prefs_project.png" />
    <figcaption>Project Preferences</figcaption>
</figure>
<p>Enter the default folder to create new projects under.</p>

<h5><a name="prefs_editor">Editor preferences</a></h5>
<figure>
    <img src="scm-workbench_files/wb_prefs_editor.png" />
    <figcaption>Editor Preferences</figcaption>
</figure>
<p>Enter the path to the editor program you want to use in the "Editor" text box.
The Browse button pops up a file picker dialog to help locate the editor program.
</p>
<p>Any command line arguments can be entered in the "Editor Arguments" text box.
</p>

<h5><a name="prefs_shell">Shell preferences</a></h5>
<figure>
    <img src="scm-workbench_files/wb_prefs_shell.png" />
    <figcaption>Shell Preferences</figcaption>
</figure>

<p>Choose the "Terminal Program" you wish to use for the <a href="#folder_action_command_shell">Command Shell</a> command.
The available choices depend on your operating system:
</p>
<ul>
<li>Windows: CMD, PowerShell and bash</li>
<li>macOS: Terminal and iTerm</li>
<li>Unix (Linux, *BSD, etc): konsole, gnome-terminal, xfce4-terminal and xterm</li>
</ul>

<p>The optional "Terminal Init Command" will be run each time a new Command Shell is created.
For Unix and macOS the terminal init command it sourced into the shell, which allow environment variables to be set.
</p>

<p>Choose the "File Browser Program" you wish to use for the <a href="#folder_action_file_browser">File Browser</a> command.
The available choices depend on your operating system:
</p>
<ul>
<li>Windows: Explorer</li>
<li>Mac OS X: Finder</li>
<li>Unix (Linux, *BSD, etc): nautilus, konqueror, thunar and dolphin</li>
</ul>

<h5>Commit Log History preferences</h5>
<figure>
    <img src="scm-workbench_files/wb_prefs_commit_log_history.png" />
    <figcaption>Log history Preferences</figcaption>
</figure>

<p>The "Commit History" and "Log History" commands will use the
values you set in this preference panel as the defaults.</p>

<h5>Fonts preferences</h5>
<figure>
    <img src="scm-workbench_files/wb_prefs_fonts.png" />
    <figcaption>Fonts Preferences</figcaption>
</figure>

<p>Choose the fonts that you wish SCM Workbench to use.</p>
<p>The Code Font is used to show differences and commit messages all other text uses the User Interface font.</p>
<p>The Code Font must be a mono-spaced font.</p>

<h5>Git preferences</h5>
<figure>
    <img src="scm-workbench_files/wb_prefs_git.png" />
    <figcaption>Git Preferences</figcaption>
</figure>

<p>Choose the "git" program that you wish to use.
The Browse button pops up a file picker dialog to help locate the git program.</p>

<h5>Hg preferences</h5>
<figure>
    <img src="scm-workbench_files/wb_prefs_hg.png" />
    <figcaption>Hg Preferences</figcaption>
</figure>

<p>Choose the "hg" program that you wish to use.
The Browse button pops up a file picker dialog to help locate the hg program.</p>

<h5>Svn preferences</h5>
<figure>
    <img src="scm-workbench_files/wb_prefs_svn.png" />
    <figcaption>Svn Preferences</figcaption>
</figure>

<p>There are no Subversion specific preferences at this time.</p>

<h4><a name="file_view_log"><a href="#menus">Menu:</a> <a href="#menu_file">File</a> » View log</a></h4>

<p>All the messages that you see in the main windows are also write to a log file.
This menu allows quick access to that log file.
</p>

<h4><a name="file_exit"><a href="#menus">Menu:</a> File » Exit</a></h4>

<p>Quit SCM Workbench. All open SCM Workbench windows will be closed.
</p>

<h4><a name="file_clear_log"><a href="#menus">Menu:</a> <a href="#menu_file">File</a> » Clear log</a></h4>

<p>Clear the log messages windows.
</p>

<h3><a href="#menus">Menu:</a> <a name="menu_view">View</a></h3>
<h4><a name="view_show_control_changed"><a href="#menus">Menu:</a> <a href="#menu_view">View</a> » Show Controlled and Changed files</a></h4>

<p>Show Controlled and Changed files that are part of the project in the list panel.</p>

<h4><a name="view_show_control_unchanged"><a href="#menus">Menu:</a> <a href="#menu_view">View</a> » Show Controlled and Not Changed files</a></h4>

<p>Show Controlled and Not Changed files that are part of the project in the list panel.</p>

<h4><a name="view_show_uncontrol"><a href="#menus">Menu:</a> <a href="#menu_view">View</a> » Show Uncontrolled files</a></h4>

<p>Show Uncontrolled files that are not part of the project in the list panel.
</p>

<h4><a name="view_show_ignored"><a href="#menus">Menu:</a> <a href="#menu_view">View</a> » Show Ignored files</a></h4>

<p>Show Ignored files, files that the project  normally ignores, in the
list panel. Ignored files are configured in the project specific config file: .gitignore, .hgignore and .svn/config.
</p>

<h4><a name="view_unified_diff"><a href="#menus">Menu:</a> <a href="#menu_view">View</a> » Unified Diff</a></h4>

<p>Use the textual unified diff format when presenting differences.
</p>

<h4><a name="view_side_by_side_diff"><a href="#menus">Menu:</a> <a href="#menu_view">View</a> » Side-by-side Diff</a></h4>

<p>Use the graphical side-by-side diff format when presenting differences.
</p>

<p>Note: This presentation is not used when showing the differences for a folder of files, unified diff is used.</p>

<h3><a href="#menus">Menu:</a> <a name="menu_folder_actions">Folder Actions</a></h3>

<h4><a name="folder_action_command_shell"><a href="#menus">Menu:</a><a href="#menu_folder_actions">Folder Actions</a> » Command Shell</a></h4>

<p>Start a command shell which has the selected folder as its current working directory.
</p>

<p>The <a href="#prefs_shell">Shell Preferences</a> allow you to customise how the Command Shell command works.
</p>

<h4><a name="folder_action_file_browser"><a href="#menus">Menu:</a> <a href="#menu_folder_actions">Folder Actions</a> » File Browser</a></h4>

<p>Start a file browser at the selected folder.
</p>

<p>The <a href="#prefs_shell">Shell Preferences</a> allow you to customise how the File Browser command works.
</p>

<h3><a href="#menus">Menu:</a> <a name="menu_file_actions">File Actions</a></h3>

<h4><a name="file_action_edit"><a href="#menus">Menu:</a> <a href="#menu_file_actions">File Actions</a> » Edit</a></h4>

<p>Edit the selected file using the text editor configured in the <a href="#prefs_editor">Editor Preferences</a>.
</p>

<h4><a name="file_action_open"><a href="#menus">Menu:</a> <a href="#menu_file_actions">File Actions</a> » Open</a></h4>

<p>Open the selected file using the standard operating system method.</p>
<p>For example open for an HTML file will open it in your web browser.</p>

<h3><a href="#menus">Menu:</a> <a name="menu_project">Project</a></h3>
<h4><a name="project_add"><a href="#menus">Menu:</a> <a href="#menu_project">Project</a> » Add…</a></h4>

<p>The Add Project wizard guides you through the step necessary to add a project to SCM Workbench.</p>

<figure>
    <img src="scm-workbench_files/wb_project_add_methods.png" />
    <figcaption>Add project methods</figcaption>
</figure>

<p>Choose how you wish to add a project.</p>
<p>Note: The Git and Mercurial options will only appear it SCM WOrkbench found the git and hg commands.</p>

<h5>Scan for existing projects</h5>

<figure>
    <img src="scm-workbench_files/wb_project_add_scan_results.png" />
    <figcaption>Scan for existing projects</figcaption>
</figure>

<p>Workbench will start scanning from your home folder ($HOME on macOS and Unix, %USERPROFILE% on Windows) looking for projects.</p>

<p>The list only contains projects that have not been already added to Workbench.</p>

<p>Each entry in the list is the folder on disk prefixed with the type of SCM that supported it.</p>

<p>Once you see the project you want to add highlight it and click Next which will
take you to the wizard page to set the project's name.
You do not have to wait for the scan to complete.</p>

<h5>Browse for an existing project</h5>

<figure>
    <img src="scm-workbench_files/wb_project_add_browse_existing.png" />
    <figcaption>Browse for an existing project</figcaption>
</figure>

<p>Enter the path to the project that you wish to add.
The Browse button pops up a file picker dialog to help locate the project.</p>

<p>If there is a problem with the path you will see feedback on the wizard page.</p>

<h5>Clone Git repository</h5>

<figure>
    <img src="scm-workbench_files/wb_project_add_clone_git.png" />
    <figcaption>Clone Git repository</figcaption>
</figure>

<h5>Clone Mercurial (hg) repository</h5>

<figure>
    <img src="scm-workbench_files/wb_project_add_clone_hg.png" />
    <figcaption>Clone Hg repository</figcaption>
</figure>


<h5>Checkout Subversion (svn) repository</h5>

<figure>
    <img src="scm-workbench_files/wb_project_add_clone_svn.png" />
    <figcaption>Checkout svn repository</figcaption>
</figure>

<p>Enter the URL of the Subversion repository. The URL is typically
publish by the Subversion repository administrators. 
</p>

<p>You may be prompted for any username and password required to access the
repository.
</p>

<h5>Create an empty Git repository</h5>

<figure>
    <img src="scm-workbench_files/wb_project_add_init_git.png" />
    <figcaption>Init empty Git repository</figcaption>
</figure>

<h5>Create an empty Mercurial (hg) repository</h5>

<figure>
    <img src="scm-workbench_files/wb_project_add_init_hg.png" />
    <figcaption>Init empty Hg repository</figcaption>
</figure>

<h5>Project Folder</h5>

<figure>
    <img src="scm-workbench_files/wb_project_add_project_folder.png" />
    <figcaption>Project Folder location</figcaption>
</figure>

<p>Enter the path where you want Workbench to store the project files.
The Browse button pops up a file picker dialog to help choose the location.
</p>

<h5>Project Name</h5>

<figure>
    <img src="scm-workbench_files/wb_project_add_project_name.png" />
    <figcaption>Name the project</figcaption>
</figure>

<p>Enter the name that you want Workbench to use for this project.</p>
<p>Click Finish to complete adding the project.</p>

<h4><a name="project_settings"><a href="#menus">Menu:</a> <a href="#menu_project">Project</a> » Settings…</a></h4>

<p>The details of project settings are described in in SCM specific documentation:</p>

<ul>
<li><a href="scm-workbench-git.html#project_settings">Git Project settings</a></li>
<li><a href="scm-workbench-hg.html#project_settings">Hg Project settings</a></li>
<li><a href="scm-workbench-svn.html#project_settings">Svn Project settings</a></li>
</ul>


<h4><a name="project_delete"><a href="#menus">Menu:</a> <a href="#menu_project">Project</a> » Delete…</a></h4>

<p>Pop up a dialog to confirm the deletion of the selected project.
</p>

<p>This does not delete the project files, it only removes the project from SCM workbench.
</p>

<h3><a href="#menus">Menu:</a> Help</h3>

<h4><a name="help_user_guide"><a href="#menus">Menu:</a> Help » User Guide…</a></h4>

<p>Open this user guide in the systems web browser.
</p>

<h4><a name="help_about"><a href="#menus">Menu:</a> Help » About…</a></h4>

<p>Pop up a dialog that shows the version of SCM Workbench, Git, Hg, PySVN, PyQt5 and Python used.
</p>


<h2><a name="optional_software">Optional software</a></h2>

<p>SCM Workbench depends on you installing optional software to support some features.</p>

<p>SCM Workbench will search for the optional software when it starts up.
If You have install git or hg and SCM Workbench does not find software you can configure the location in the Preferences…</p>

<p>When SCM Workbench starts up it reports the location of the optional software it found.</p>
<pre>
Starting Scm Workbench
Reading preferences
Hg using program /usr/bin/hg
Git using program /usr/bin/git
</pre>

<p>More details, like version information, is shown in the <a href="#help_about">Help » About…</a> menu.</p>

<h3>Subversion (svn)</h3>
<p>Subversion is always supported by the builtin pysvn code.</p>

<h3>Git</h3>
<p>Git support requires that you install the git command for your operating system.</p>
<ul>
<li>Windows - recommended <a href="https://git-scm.com/download/win">Git installer</a>.</li>
<li>macOS - Apple ships Git 2.10.1 on macOS Sierra. However you can install a newer version using
<a href="https://brew.sh/">homebrow</a> or <a href="https://www.macports.org/">MacPorts</a>.</li>
<li>Linux - use your distributions package manager to install git.</li>
</ul>

<h3>Mercurial (hg)</h3>
<p>Mercurial support that you install the hg command for your operating system.</p>

<ul>
<li>Windows - recommended <a href="https://www.mercurial-scm.org/downloads">Mercurial Inno Setup installer</a>.</li>
<li>macOS - install Mercurial from either <a href="https://brew.sh/">homebrow</a> or <a href="https://www.macports.org/">MacPorts</a>.</li>
<li>Linux - use your distributions package manager to install hg.</li>
</ul>

<hr />
</body>
</html>
